arXiv:1503.01073vl [cs.MS] 27 Feb 2015 


T3PS vl.O: Tool for Parallel Processing in 

Parameter Scans 

Vinzenz Maurer [3 


Department of Physics, University of Basel, 
Klingelbergstr. 82, CH-fOBG Basel, Switzerland 


Abstract 

T3PS is a program that can be used to quickly design and perform parameter scans 
while easily taking advantage of the multi-core architecture of current processors. It 
takes an easy to read and write parameter scan definition file format as input. Based 
on the parameter ranges and other options contained therein, it distributes the cal¬ 
culation of the parameter space over multiple processes and possibly computers. The 
derived data is saved in a plain text file format readable by most plotting software. 
The supported scanning strategies include: grid scan, random scan, Markov Chain 
Monte Carlo, numerical optimization. Several example parameter scans are shown 
and compared with results in the literature. 
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Disclaimer: 

T3PS is published under the GNU General Public License 0 This means that you can use 
it for free. We have tested this software and its results, but we can’t guarantee that this 
software works correctly or that the results derived using it are correct. 

If you encounter any problem or have a question, feel free to contact the author by e-mail. 


^http://www.gnu.org/licenses/lgpl.html 
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1 Introduction 


T3PS is a Python program that facilitates swift and versatile implementation of parameter 
scans on mnltiple CPUs and/or compnters. 

Its main focns lies in delegation of tasks {‘^points” in parameter space) to snb-processes 
{‘^point processors" , see 2.2.5) that calculate information about these points. These sub¬ 


processes can run in parallel on one or more computers. To this end, each evaluation of a 
point works the following way: 

Each point is characterized by a list of values with hxed length. These values are 
substituted into a template file in pre-determined positions. The hie is then saved into 
a separate temporary folder and its path is given to a point processor, which returns the 
results derived from the substituted template file as another list of numbers. These numbers 
are then saved together with the previous list separated by tabulators (“\t”) to a result 
hie as a single line. Calculations can be interrupted and resumed at any tim^ 

For determining which points should be processed, the following strategies are imple¬ 
mented in T3PS: 


• Simple scan: the user directly specihes a grid, basic probability distributions or an 
explicit list of points that shall all be processed. 

• Markov Chain Monte Carlo (MCMC) algorithm: the user specihes ranges or discrete 
sets of parameter values, a propagation likelihooc0 and the number of points to 
calculate to obtain a sample for the likelihood in question. 

• Optimizing scan: the user specihes ranges or discrete sets for the values of the dehned 
parameters. Using an evolutionary algorithm, the global maximum of a user-supplied 
htness function is searched for. 

• Exploring scan: the user specihes a grid of points and a likelihood function. The 
points will be calculated gradually while aiming to hnd more likely or more interesting 
points earlier than others. 

Additionally, T3PS supports the following auxiliary modes: 

• Test mode: point values are provided by hand by the user. This is useful for checking 
the implementation of a given point processor and scan dehnition before committing 
to a lengthy parameter scan. 

• Worker mode: This mode is used only in setups involving multiple computers. In 
this mode, the running instance of T3PS does not come up with new points on its 
own but rather waits for a “manager” process to supply them. 

^T3PS will try to resume at the exact step it was interrupted at, but this may not always be possible 
due to constraints of the algorithm or implementation. 

^In the case of uniformly distributed parameters, this is exactly the target probability distribution 
function. 
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This manual is organized the following way: after a quick introduction to T3PS in 
sec. |1.2| the general structure, strategies and concepts of typical parameter scans are shown 
in 0 In sec. the scan dehnition format is introduced and all possible dehnition directives 
are listed and explained. The command line interface is detailed in sec. In sec. the 
implementation of multi-computer calculations is described. Finally in sec. the already 
implemented and included point processors are documented. Everything is put together in 
several example scans in sec. 

1.1 System Requirements 

The following software packages must be installed for T3PS to run: 

• Python 2.7 or compatible, e.g. PyPy 1.5 or higheij^ 

• Unix-like operating system 


1.2 Installation and Quick Start 

T3PS is usable right after extracting its archive hie and possibly making the main hie 
executable: 

$ tar xvfz T3PS-1.0.tar.gz 
$ cd T3PS-1.0 
$ chmod u+x src/t3ps 
$ ./src/t3ps scan_definition.scan 


For easier usage, it can also be properly installed using 
$ make install 

which (after a prompt to the user) will copy T3PS to an installation folder and will create 
a link such that T3PS can be launched by simply typing 

$ t3ps 


As an introduction, we will now show how to perform a very basic scan. We begin with 
the scan dehnition hie called “QuickStart.scan”: 

[setup] 

point_processor = processors/SimpleProcessor.py 
template = QuickStart.function 

[SimpleProcessor] 

# do a scan with the 'basic calculator' 

# with basic mathematical functions 
program = be —mathlib 


"’^Note that two of the examples in sec. 7.2 use the Python module “SciPy”, which is as of writing 
this manual not fully available for PyPy. It may thus not run completely unchanged and out of the box 
compared to using standard CPython. 
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[parameter_space] 

# two parameters called x and y 
par_names = x, y 

# define each parameter to take 100 different 

# values going from -1 to 1 

par_x = interval(-1, 1) with count = 100 
par_y = interval(-1, 1) with count = 100 

The point processor called SimpleProcessor (included in the T3PS package) will use 
the basic calculator be to calculate the mathematical function sin(a;^ + y) cos(j/^ + 3x) by 
inserting the x and y values into the template file with the name “QuickStart.function” 
and the following content^ 

s( ($x)“2 + ($y) ) * c( ($y)"2 + 3 * ($x) ) 


The only thing left to do for the scan is launching T3PS using 
$ t3ps QuickStart.scan 

After a short while in the command line interface of T3PS, the resulting data set can be 
plotted in Wolfram Mathematica® [1] using the code 

points = Import ["QuickStart.scan.data", "Table"]; 

ListContourPlot[points [[All, {1,2,3}]]] 

and in gnuplot |2] using the code 

splot "QuickStart.scan.data" using 1:2:3 

For examples that go more in-depth and show more features, see sec. 


2 Overview 

2.1 Scanning Strategies 

We will now go into more detail how each scanning strategy behaves and is (roughly) 
implemented. For more detailed sketches of the actual implementations, see app. 

Scan This mode simply processes a defined set of points in the specified parameter space. 
There are three basic modes for specifying it. 

In the hrst mode, the user specihes the parameter space as a grid dehned as the direct 
product of hnite ranges for each parameter. It is then scanned over by simple iteration 
over all points on the grid. This mode is called “grid” mode. 

If one or more parameter range is continuous, but the full space is still a direct product, 
the second mode applies. Here a user-specified number of points in parameter space is 
randomly chosen (according to their distribution) and calculated. T3PS calls this mode 
“scatter”. 

®In be, s and c denote the sin and cos functions respectively. 
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Figure 1: Flow chart representing the overall algorithmic structure of a scan in T3PS. The 
main program takes the information provided by the scan dehnition hie and distributes the 
work to a certain number of concurrently running point processors, one point each. These 
in turn calculate data using some (possibly external) code and return the relevant data. 


In the third mode, instead of a parameter space as direct product of ranges, the user can 
supply a hie in tabulator separated values (TSV) format that specihes the set of possible 
parameter value combinations that constitutes the parameter space. This mode is called 
“hie” mode. 


MCMC This mode uses a standard Metropolis-Hastings algorithm to draw random 
samples of points from a more complicated probability distribution. This is also known as 
a Markov Chain Monte Carlo (MCMC) method. 

The range for each parameter can either be given a set of discrete and equally probable 
values or as continuous values following some (simple) probability distribution. In both 
cases, the user can supply a step size for a Gaussian proposal density around the parameter 
value of the previous iteration. If no step size is given, the specihc point coordinate is 
chosen at random from their prior probability distribution given by the parameter range 
dehnition. 

Once a Markov chain reaches a user-supplied number of sample points (not taking into 
account non-trivial stay counts), it terminates. 


For a sketch in pseudocode of the implementation in T3PS, see sec. A.l 


Optimize This mode implement^ a diherential evolution algorithm [5] to optimize a 
user-supplied htness function. Here, T3PS tries to hnd the global htness maximum by 
(starting from a randomly found or user-supplied initial population of points) repeatedly 
applying an evolutionary approach that yields a new - better or same quality - population 
in each iteration. 

It stops once the best found htness has not changed by more than a user-supplied 
threshold value for a user-supplied number of iterations. If the full parameter space has 

®This is also implemented in the NMinimize/NMaximize functions of Wolfram Mathematica®. 
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only a finite amount of points, this mode caches calculation results and thus never calculates 
points twice. 


For a sketch in pseudocode of the implementation in T3PS, see sec. A.2 


Explorer This mode implements a custom swarm type algorithm acting on a discrete 
hnite grid, analogous to the plain “scan” mode. Starting from randomly found or user- 
supplied points and emanating from further calculated points, the neighbor points (relative 
to the grid) of a subset of points are calculated in each iteration, where points with a higher 
value of a user supplied “likelihood” function take precedence over ones with lower values. 
T3PS keeps track of all calculated points and no point is processed twice (some memory 
usage optimizations can change this slightly). Since on a hnite grid calculation time is also 
hnite, this is just a re-ordering compared to doing the same calculation in “scan” mode. 
However, if one is only interested in points satisfying a particular needed level of likelihood, 
this method can save time when dealing with extensive parameter spaces (depending on 
the starting points), while still benehting from the regularity and controllable density of 
grid-form parameter spaces. 

An additional feature is the specihcation of projections over which a function shall 
be maximized (not necessarily the “likelihood” function). When the user specihes such a 
projection, T3PS groups up all known points by two (user supplied) coordinates x, y and 
third coordinate z (default is the “likelihood”). Then the points with maximal z coordinate 
Zmax for each point in the x, y plain are used hrst as site for the calculation of further 
neighbor points. In addition to simple neighbors, these optimal points are interpolated 
and extrapolated to smoothen out the projected x-?/-Zmax grapliQ 

More specihcally, the algorithm has three states. In state one, only one point with 
maximal z per x and y is found and has his neighbor points and extra-/interpolated pseudo¬ 
neighbors calculated. If the algorithm does not hud any new points this way, it goes into 
state two and instead looks for the points maximizing z while being on the boundary of 
the point set, i.e. ones that have some missing neighbors, and calculates those missing 
neighbors. In the case, where the algorithm does not hnd any new points in state two, 
it goes into state three, where projections are not considered and just a set of pre-dehned 
number of boundary points with sufficient likelihood has their neighbors calculated. 

If there are no projections dehned, the algorithm always automatically goes into state 
three. If there are projections dehned, every time new points are found the algorithm 
reverts back to state one. 

Moreover, in the case where approximate symmetries of the parameters are known 
under which the results are almost invariant, these can also be specihed and used in state 
one to further rehne the x-y-Zyaa.x graphs by applying the corresponding transformations 
to the points with maximal coordinate in each plain. 

Note that there is no automatic convergence analysis and users must decide for them¬ 
selves whether or not the calculation has run long enough. T3PS only calculates some 

^Thus projections work best if the 2 coordinate function is sufficiently linear over the scale of the grid 
spacing. 
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possibly helpful indicators involving the change in the projection plains and other charac¬ 
teristics between each iteration. 


For a sketch in pseudocode of the implementation in T3PS, see sec. A.3 


Worker As a worker instance, T3PS will not start any calculations on its own, but 
will listen on a user-supplied network port (default: 31415) for calculation requests from 
T3PS manager instances. To make sure only appropriate processes make these requests a 
shared secret also referred to as “authorization key” must be specihed. This key has to be 
distributed among the involved T3PS instances and scan dehnition hies. 

For more details on this mode, see sec. 


Test This mode can be used to test the formulas and other general directives given in 
the scan dehnition hie. For this, T3PS will process points in parameter space that are 
supplied directly by the user and only indirectly consider parameter ranges specihed in the 
scan dehnition hie. Specifying points can either be done via the command line argument 
“—pars” (see sec. or directly via a prompt on the terminal. Input via the terminal will 
be saved for later re-use and can be accessed via arrow up and down keys. Calculation 
results will also be saved. Additionally, the user can choose to run the calculation on one 
of the conhgured T3PS worker instances. 


2.2 General Concepts 

2.2.1 Running of External Code 

To make it possible to run more than one process in parallel, T3PS will create temporary 
directories, in which each process will run. This means that, in general, external code must 
make no assumptions on the location of the current directory and must be able to run 
from any directory on the computer. In addition, any side-ehects outside of the current 
directory should be minimal - this also means that external code should generally be what 
is usually referred to as “re-entrant”. 

2.2.2 Structure and Storage of Results 

Every result of processing a parameter point consists of three parts: 

Parameters A parameter is a value taken from a specihed range. The parameters directly 
and uniquely label every point in the parameter space. 

Variables A variable is a simple function of the parameters. They are calculated before 
substituting anything into the template file. This can be used to re-parametrize the 
calculation, e.g. from a, b to a/6, a-b, or to obtain values following more complicated 
distributions than what is currently supported for parameters in T3PS. 


Data This denotes all values as derived and returned by the point processor^ see sec. 


2.2.5 




Each line in the result hie is then a tabulator separated list of values consisting of either 
the concatenation of these three sub-lists of values (customizable in “scan” mode) for valid 
points or only parameter values and exclusion reason for invalid ones. Each point has to 
fulhll the following two criteria to be considered valid: 

No Error The point processor must have successfully returned, i.e. no error must have 
occurred (“Python has not raised an exception”). This usually also means that 
external programs must have exited with an error code of 0. 

Inside Bounds The three sets of values of above have to satisfy a list of user-supplied 
bounds/constraints. 

The tabulator separated format can be read directly by gnuplot |2] and by Wolfram 
Mathematica® PP (using its import function). 

As result from performing a scan dehned in the hie “name.scan”, T3PS generates the 
following hies in the current working directorjj^ 

name.scan.log Log hie containing the most important messages from T3PS. (Mode: all) 

name.scan.data Valid result points. One line per point in parameter space, tabulator 
separated values. In “optimize” and “explorer” mode, one additional column is 
appended containing the htness function or likelihood value. (Modes: all except test, 
worker and mcmc) 

name.scan.excluded-data Excluded result points. Same format as “.data” hies except 
for a single column prepended containing only the character ‘E’ for error/exclusion. 
The columns following that contain the parameter values and the reason for exclusion 
or error message as text. Note that upon importing data formatted like this, T3PS 
will silently ignore the hrst column (‘E’). (Modes: all except test, worker and mcmc) 

name.scan.resume Current resume position. (Mode: scan) 

name.scan.speed Current statistical information on the speed of the calculation. This 
will be regenerated over time if deleted. (Mode: scan, mcmc) 

name.scan.testhistory History of user supplied input points in “test” mode. History hie 
format of readline library. (Mode: test) 

name.scan.testdata Valid points obtained during calculations in “test” mode. Same 
format as “.data” hie. Likelihood value is appended to each row if dehned. (Mode: 
test) 

name.scan.chain.i Valid points obtained from the Tth Markov chain (starting from i = 0). 
Lines include likelihood and stay count at the end for every point in addition to 
parameters, variables and data. Otherwise, same format as “.data” hie. (Mode: 
mcmc) 

®One can change this with the command line argument —output_dir. 
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name.scan.rejected.* All valid but rejected data points that the i’th Markov chain (start¬ 
ing from * = 0) encountered, i.e. those that were discarded only due to random chance. 
Rows include the likelihood at the end for every point in addition to parameters, vari¬ 
ables and data. Otherwise, same format as “.data” hie. (Mode: mcmc) 

name.scan.work Set of points that were determined to be calculated next in a previous 
run of T3PS. This is used to resume calculations without the need to regenerate this 
information. (Mode: explorer) 

name.scan.boundary Cache for the determination of boundary points, i.e. points that 
are not invalid and have missing neighbor points. (Mode: explorer) 

name.scan.projectedpoints Parameter values (TSV format) of the set of points that 
were determined to have maximal 2 ; value in each of the projections. This can be 
used to do the minimal amount of calculation necessary to re-calculate all projection 
graphs. This is only updated during state one iterations. (Mode: explorer) 

name.scan.projection.* The x-y-Zi^s.^ graph of the *’th projection (starting from * = 0) 
in TSV format (only updated in state one). This is also used to assess the difference 
of the projection plains between successive state one iterations. (Mode: explorer) 

name.scan.population Last used population in the differential evolution algorithm. The 
points are contained as lines consisting of likelihood and parameter values (in that 
order) separated by tabulator characters. (Mode: optimize) 

name.scan.optimum Parameter point that maximizes the likelihood function. Same for¬ 
mat as “.population” hies. (Mode: optimize) 


2.2.3 Formula Input 

T3PS understands and uses formulas in the form of Python code in several places in the 
scan dehnition hie. They are compiled to Python bytecode and evaluated according to the 
following rules: 


• Parameter, variable and data values of each point in parameter space can be accessed 
using “pars . NAME” , “vars . NAME” and “data. NAME” , where NAME is a name as given 
in the scan dehnition hie. Alternatively, the syntax “list [*]”, where list can be 
pars, vars or data, can be used to access the value of the *’th value with * starting 
from 0. Note that it is not possible to have unnamed parameters or variables, while 
unnamed data values are allowed but only at the end of the list of data values and 
are only accessible using “data [*] ”. 


In some cases, only a subset of these values can be available, for more details see the 
relevant formula directive description. For rules on what constitutes a valid name, 
see the description of par_naines in sec. 


3.3 


10 



• In Python formula expressions, you can use all built-in Python functions as well as 
several functions and constants from the Python module “math”|^ simply by name. 


One can provide access to more Python modules using the directive helper_modules 
in the setup section, see sec. 3^ 


• The output of formulas is assumed to be a single value unless stated otherwise (being 
something else leads to undehned behavior). If this is not the case, it will be clearly 
mentioned in the relevant scan dehnition directive description. 


• Formulas for variables are evaluated in the order in which they are saved to the result 
hie. Variables calculated hrst can not directly depend on variables coming later. 
However, to circumvent this limitation, T3PS provides the “remember” function to 
remember values computed in formulas before. 

Usage: 

# setting values 
remember (var=value) 

# retrieving values 

remember( "var") 


• All formulas are evaluated with Python’s hag for “future division” enabled. This 
means that contrary to ordinary Python code the division of two integers using the 
operator yields a boating point number and not an integer. Standard integer 
division can still be done using ‘//’. 

Example: “l / 2” ->0.5, “l // 2” -> 0. 

• Exceptions/errors (e.g. division by zero or invalid indexing) occurring in formulas for 
variables and bounds simply count as a reason for exclusion of the parameter point. 
Exceptions in all other formulas lead to a complete stop of the running scan, unless 
stated otherwise. It is advised to make use of the “test” mode to catch ill-dehned 
formulas early before they generate large erroneously excluded data sets. 

Examples for formulas: 

# A_0 = 

pars.aO * pars.mO 

# likelihood for Higgs mass fit = 
exp(-0.5 * ((data.mhO - 125.7) / 0.4) ** 2) 

# P_ee (electron neutrino survival probability) 

1 - sin(2*pars .theta) ** 2 * sin ( 

vars.deltaml2sqr * pars.L / 4 / pars.E 
) * * 2 

# bound check for BR(mu -> e gamma) 
data .BR_muegamma < 2.4e-12 


®The full list of exposed math functions is: sin, cos, tan, asin, acos, atan, atan2, exp, log, loglO, sinh, 
cosh, tanh, asinh, acosh, atanh. The only exposed constant is pi. Other functions “/” from the math 
module can be accessed as “math./” 
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2.2.4 Template File 


The template file is a file containing special text fragments that are replaced with (pa¬ 
rameter or variable) values specihc to the currently processed point in parameter space. 
The possible forms for these placeholder text fragments are similar to Unix shell variable 
interpolation and are given by: 

$valueidentifier This will be replaced with the value corresponding to the point in 
question, valueidentifier can only contain letters, numbers, underscore and dot. 
The hrst character not conforming to this terminates the placeholder specihcation. 

This provides access to parameters and variables of a point through the placeholder 
fragments “$pars.NAME” and “$vars.NAME” with the same rules for NAME as in 
input formulas. In addition, both sets of values together can be accessed directly 
using “$name”, where parameter names take precedence before variable names. 

${valueidentifier} Equivalent to the placeholder fragment “$valueidentifier” ex¬ 
cept that the identiher can also contain the square bracket characters ‘[’ and ‘]’. This 
is also useful if valid valueidentif ier characters follow the placeholder fragment. 

Examples: 

“${intpart}.${fracpart}”, “${vars [ 0]}” 

$$ This placeholder will be replaced with the letter 

In the following, substituted template file will refer to the template hie with all of its 
placeholders replaced with the values belonging to the current point in parameter space. 

2.2.5 Point Processor 


The point processor is a Python module containing a function “main” with either one or 
three arguments, namely the path of a substituted template file and parameter and variable 
values. This function can thus either have the signature 



The “main” function must return an object of type “list” (or another iterable type) con¬ 
sisting of the derived values. 

For more advanced purposes, the point processor module can additionally contain a 
function “init”, which is called with the following arguments: the folder of the scan 
dehnition hie, the Python SafeConhgParser object containing the scan dehnition directives 
and the Python module containing all functions and classes of T3PS. It has the signature 
def init (definition_file_path, config_object, module): 
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This can be used to initialize any internal structures depending on specifics of the scan def¬ 
inition. For an example, see the source code of the “ExampleProcessor” point processor 
provided with the T3PS package. 

In practice, the point processor module’s main function should be as simple as possible 
and should directly call another process and then parse its output for the data relevant 
for the calculation. Since each new process that is started during point processing, e.g. 
a shell or other language interpreter, increases the calculation time, this can lead to - 
depending on the overall performance - significant delays for large parameter spaces. It is 
thus recommended to try to minimize the amount of added complexity in the processing 
of a point. 

For an overview of point processors already included in T3PS, see sec. 


3 How to define a Scan 

This section covers the scan definition file format of T3PS with all currently available 
directives. 

3.1 Definition File Format 

The scan definition file format is based on the one accepted and processed by the Python 
module SafeConfigParser [6], which is very similar to one of standard “.ini” files as used 
by Microsoft Windows®. Each file consists of one or more sections labeled by the line 
“ [section_name] ”. Each section consists of lines of name, value pairs of the form 
“naine=value” or “nameivalue” , with names specific to that section. It is not neces¬ 
sary to put quotation marks around a string value. Trailing whitespace in names and 
leading and trailing whitespace in values as well as trailing whitespace on every line is 
removed, and multi-line values can be given by indenting lines after the one with “name”. 
Additionally, all names are case-sensitive and later specifications with the same name and 
section simply overwrite earlier ones. 

Comments are given by lines starting with “#” or Additionally, comments in 

otherwise non-empty lines can only be made using and only if there is whitespace in 
front of it. 

The SafeConfigParser module also supports text substitution. This means values can 
contain references to other values in the same section (or optionally in a special section 
called “default”). These references are then replaced with the referred to (final) value for 
the full evaluation of the directives. An example for the scan definition file syntax is given 
by: 

# comments look like this 
[section] 
version : 1 

information = This config file has one quite long 
but uninformative multi-line value 
dir = IGNORED 


13 





template = % (dir)s/file 

point_processor = % (dir)s/FullCalculation.py 
dir = folder 

one_hundred_percent = 100%% 

This replaces the text fragment “% (dir) s” with “folder” in the directives template and 
point_processor, such that the template directive now has the value “folder/hle”. 
Note that the value “IGNORED” is ignored since it has been overwritten by setting dir 
a second time. Note that, to write actual ‘%’ characters, one must instead write 

Please keep in mind that text substitution into formulas leads to direct evaluation 
of the substituted text fragment by Python. Thus the value string “% (x) s ** 2” with 
X being set to “-1” is substituted by SafeConhgParser to “-1 ** 2”. Due to operator 
precedence. Python evaluates this expression to -1. In contrast, the formula “pars .x ** 
2” is correctly evaluated to +1. 

Beyond the default SafeConhgParser features, T3PS also supports the inclusion of other 
hies using the syntax: 

@include PathToFile 

This causes the hie accessible under the path “PathToFile” to be parsed directly as is at 
the position of this statement. In particular, multi-line values can be started in the parent 
hie and be continued in the included hie. If the given path is not absolute, the hie is looked 
for in the following folders (in order): 

• the current folder, from which T3PS was run. 

• the folder containing the main scan dehnition hie, i.e. the one that was not subject 
to @ include somewhere and was given last on the command line if applicable. 

• the folder containing the T3PS executable hie. 

• the folder containing the real T3PS hie if it was launched through a symbolic link. 

Note that, as usual in Unix shells, paths starting with “'” or “'username” have this 
initial part replaced with the respective user’s home directory. 

3.2 The “setup” Section 

This section contains the directives concerning the general setup of the calculation. 

version (integer) This specihes which T3PS version the scan dehnition is written for. 
Defaults to 1. 

In future versions of T3PS, this will be used to enable backwards-incompatible fea¬ 
tures (the default value will not change). 

mode (string) Can be one of “scan”, “mcmc “, “optimize”, “explorer”, “test” or “worker”. 
Specihes which scanning strategy should be employed. Can be overwritten using the 
“ — mode” command line argument, see sec. 
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concurrent_processors (integer) Specifies the number of concurrently running pro¬ 
cesses that T3PS should use on the running computer. This does not affect worker 
instances running on other computers. For more details, see sec. 

This defaults to the number of processor cores of the running computeif^ 


template (path) The path to the template file. If this directive is not present, T3PS will 
not perform the actions outlined in sec. 2.2.4 and the template argument passed to 
the point processor’s main function will be ‘None’. 

This directive follows the same search rules for paths as the include” statement. 


point_processor (path) The path to the source code hie of the point processor that 
is used to calculate points. Note that it must be implemented in Python (or as a 
wrapper written in Python) and must be importable without errors. If not given, 
T3PS will only calculate variables and no data values. 

This directive follows the same search rules for paths as the “@ include” statement. 


helper_modules (string) List (separated by ‘:’) of module names or paths to Python 
module hies that shall be made available to the evaluation of input formulas. If 
given as path to a hie, a module can be accessed by itsbare hie name, i.e. without 
folder and extension. 

Each module path is resolved using the same search rules for paths as the include” 
statement. 


3.3 The “parameter_space” Section 

This section can contain the following directives: 

par_names (string) List of names (separated by comma) given to the parameters. Whites¬ 
pace around list elements is stripped. Names can contain letters, numbers and un¬ 
derscore, but must not start with a number or underscore, must not be empty or a 
Python keyword and must not be in the list multiple times. 

par_name (range) The value range for the parameter called name. A valid range is given 
by “definition [with options], where options can be a comma separated list 
of “name=value” pairs while definition can be one of the following 

• a hnite list of numeric values, e.g. “l, 2, 3, 4”. Intermediate values can 
be replaced with an ellipsis “...” or with at least two values preceding 
and one following the ellipsis, e.g. “l, 1.2, . . 2”. Such an expression 

^*^Note that for processors with hyper-threading capability or similar, this may give the number of logical 

cores instead of physical ones. 
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“a, b, . . c” will be expanded to the list of numbers starting at a and 
going to c with step size b - a. Example: 

“1, 1.2, 2”{1,1.2,1.4,1.6,1.8,2} 

The values a, b and c will always be part of the value range even if c is not 
exactly encountered using this expansion. 

• an interval dehnition as in “interval (a, b)”. This range type supports the 
options count and distribution. The latter can be either “linear” or “log” 
specifying whether the parameter or its logarithm shall be uniformly distributed. 
If “count” is given, the range is automatically translated into a hnite range with 
appropriate equidistant (linear or log) spacing and as many points. Example: 

“intervai{l, 2) with count=5” 
^{1,1.25,1.5,1.75,2} 

• the dehnition of range with a Gaussian distribution with mean mu and standard 
deviation sigma written as “normalvariate (mu, sigma)”. This range type 
also supports the option “count”, which automatically translates the range into 
a discrete and smoothly spaced set of values also following a normal distribution. 
Example: 


“normaivariate(1, 2) with count=ll” 
{-1.77, -0.94, -0.35,0.14,0.58,1.00,1.42, 
1.86,2.35,2.94} 


In “mcmc”, all parameter ranges can also have the option “mcmc_stepsize”. For 


details, see sec. 3.5 


var_naines (string) Comma-separated list of names for the variables. Same rules and 


behavior as for 


par_names 


var_name (formula) Formula for calculation of the variable called name. Follows the 
formula input format detailed in sec. 2.2.3 Can only depend on parameters and 
constants. Variable formulas are evaluated in the order in which they appear in 
var_naines. Errors (e.g. division by zero or invalid indexing) occurring during the 
evaluation of these formulas will lead to exclusion of the point. 


Examples for variables: 

# Bino mass M_1 = r_l M_{l/2} 
var_Ml = pars.rl * pars.M12 

# Trilinear coupling (A_u)_{33} = A_t y_t 
var_Au33 = pars.A_t * (pars.m_t / 174) 
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data_names (string) Comma-separated list of names for the data values. Same rules as 
par_naines and var_naines. If the point processor returns more values than names 
are given here, the excess values can be accessed by their index i (starting from 0) 
using the syntax “data [i] ”• 

bound_count (integer) The number of user-dehned bounds or validity checks performed 
for each point in parameter space. Defaults to 0. 

bound_i (formula) Formula for the i’th constraint check (starting from i = 0) performed 
for each (otherwise valid) point in parameter space. Should compute a value that can 
be interpreted as True or False. Note that you must dehne at least as many bounds 
as specihed in bound_count, while surplus bounds are ignored. 

The check is performed only after the point in parameter space has been handed 
over to the point processor and the calculation has hnished, i.e. “data” values are 
always available. The constraint checks are not evaluated if the point processor itself 
has generated an error. 

This has the same semantics regarding exceptions/errors as var_name, i.e. errors 
lead to exclusion of the point. 


3.4 Scan Mode Specific Directives 

In addition to the generally applicable directives above, the “scan” mode has the follow¬ 
ing modihed semantics and directives. Directives written as “[section] name” refer to 
“name” in the section “section”. 

[setup] unit_length (integer) The number of points that are processed in one batch. 
This means that for each scan iteration a set of points with length given by this 
directive of not yet calculated points is selected and handed over to all running 
point processor processes. The Python multiprocessing module ensures that the 
set is evenly distributed across all of them. After all points in the set have been 
processed, the results are saved to the “.data” or “.excluded-data” hies (depending 
on the validity of the specihc point). 

It is generally advised to set this value high enough so that the waiting time for 
all processes to hnish is not large compared to the full processing time of the set of 
points in parameter space. 

Defaults to 100 ■ concurrent_processors. 


[parameter_space] mode (string) Can be either “grid” (default), “scatter” or “hie”. 


In “grid” mode, the usual interpretation of parameter dehnitions as described in sec. 


3.3 applies and all parameter ranges must be hnite. 


In “scatter” mode, a random sample of points is drawn from the parameter ranges to 
be processed. The number of points can be adjusted using the directive point_count 
in the parameter_space section. 
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In “file” mode, the parameter space is not given by the Cartesian product of pa¬ 
rameter ranges, but by pre-determined parameter space points given in the hies in 
the directive files of the parameter_space section. In this case, the directives 
“par_name” in the parameter_space section are interpreted as input formulas (as 
detailed in sec. 2.2.3) that, however, only have access to the “file” values instead of 
“pars”, “vars” or “data”. These “file” values correspond to the columns (tabu¬ 
lator separated) of each line in the hies specihed in the files directive. They can 
be accessed by index or via the names specihed in the file_columns directive. 


[parameter_space] point_count (integer) The number of points that should be cal¬ 
culated. Only applies in parameter space mode “scatter”. 

[parameter_space] files (string) List of hie names separated by (whitespace is 
signihcant except for leading and trailing one of full lines!) to be used as dehnition of 
the parameter space. Only applicable in “hie” parameter space mode (or “explorer” 
mode). 

If the command line parameter —output_dir is set and a path is just a hie name, 
it is hrst looked for therein. Otherwise, each path is resolved using the same search 
rules as the “@include” statement. Lines starting with a column containing only 
‘E’, i.e. lines containing excluded points, are ignored. 

[paraineter_space] file_columns (string) List of names (separated by comma) given 
to the columns in the hies given in the directive files. Same rules and behav¬ 
ior as “par_naines”, “var_naines” and “data_naines” . Only applicable in “hie” 
parameter space mode. 

[algorithm] out_colviinns (formula) List of formulas separated by comma^^ specifying 
what values should be saved to the “.data” hie. Can be used for e.g. re-ordering or 
re-parametrizing of the result values. The formulas have access to “pars”, “vars” 
and “data” (as well as “file” values in “hie” mode). 

If not given, T3PS saves all data as usual (excluding “file” values). 


3.5 MCMC Mode Specific Directives 

In addition to the general directives, this mode also has the following changed semantics in 
the sections setup and parameter_space and its own directives in the algorithm sec¬ 
tion. Directives written as “[section] name” refer to “name” in the section “section”. 

[setup] unit_length (integer) The number of distinct points, i.e. not weighted by stay 
count, each Markov chain shall hnd. 

Commas inside the formulas are handled correctly as long as all brackets and quotation marks are 
properly closed and opened. 
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[setup] concurrent_processors (integer) T3PS runs this many chains in parallel on 
the local computer. 

[parameter space] par_name (range) In “mcmc” mode, all ranges can also have the 
option “mcmc_stepsize” that specihes the step size for the Gaussian proposal den¬ 
sity around the parameter value of the last iteration. For discrete parameter ranges, 
this is understood to work on the indices into the list of values, i.e. the result of the 
proposal density sampling is rounded to the nearest integer). 

[algorithm] likelihood (formula) Formula for the calculation of the propagation like¬ 
lihood. This formula has to evaluate to non-negative numbers for all valid points in 
parameter space. Its value is also saved together with the stay count in the resulting 
“.chain.*” hies. Points with vanishing likelihood value are always rejected. To ht 
a data value to a measurement with mean /i and uncertainty a, the likelihood 
should be given by: 

likelihood = exp{ 

-{data.x - /*) ** 2 / {2 * a ** 2) 

) 


Beyond hxing the length of all chains, T3PS does not perform any convergence analysis. 

Note that this mode does not support distributing the calculation to more than one 
computer using the manager/worker architecture. However, since Markov chains work 
autonomously, this can be done by hand by starting T3PS on each computer in “mcmc” 
mode separately. 

3.6 Optimize Mode Specific Directives 

This mode also has slightly adjusted semantics for the scan dehnition directives. Addition¬ 
ally, there are new directives in the algorithm section, which make it possible to adjust 
the different parameters of the differential evolution algorithm [5]. Directives written as 
“[section] name” refer to “name” in the section “section”. 

[setup] unit_length (integer) The used population size. Defaults to 10 • D, where D 
is the number of parameters with at least two possible values. 

[algorithm] likelihood (formula) The htness function that is maximized. No restric¬ 
tions are placed on its value beyond being a real number. 

[algorithm] waiting_threshold (float) The maximal absolute change in the htness 
function that is not considered convergent behavior. Defaults to 0. 

[algorithm] waiting_threshold_relative (hoat) The maximal relative change in 
the htness function that is not considered convergent behavior. Defaults to 10"'^/^, 
where rj is given by the machine precision (16 in the case of double precision). 
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[algorithm] waiting_time (integer) The number of iterations, during which the change 
in the likelihood function value is below the one governed by the waiting thresholds, 
that the algorithm should wait to make sure convergence has really taken place. De¬ 
faults to 10 • D, where D is the number of parameters with at least two possible 
values. 


[algorithm] differential_weight (float) The differential weight as used in differen¬ 
tial evolution, see sec. |A.2[ Defaults to 0.6. 

[algorithm] crossover_probability (float) The cross-over probability as is used in 
differential evolution, see sec. A.2 Defaults to 0.5. 

In summary, the htness / is considered to have converged if 

\f^-fi+l\<€ + p\f^\ , 


for at least waiting_time+l consecutive iterations i, where e is determined by the direc¬ 
tive waiting_threshold and p by the directive waiting_threshold_relative. Note 
that, due to the random nature of the algorithm, this does not make a statement on the 
precision of the obtained optimal point or htness. 


3.7 Explorer Mode Specific Directives 

The “explorer” mode has the following semantics and custom directives. Directives written 
as “[section] name” refer to “name” in the section “section”. 

[setup] unit_length (integer) Generate this many random points as initial point set. 
During running, neighbors of (at most) this many points are calculated when no pro¬ 
jections are done in that iteration, i.e. state three. This directive has no consequence 
in projection-enabled iterations (state one or two). 

Defaults to 10 • D, where D is the number of parameters with at least two possible 
values. 

[algorithm] loading_filter (formula) Formula analogous to “bound_z” in the sec¬ 
tion “parameter_space” that can be used to specify a condition that points have 
to satisfy to be loaded from disk into memory. Note that this only applies to loading, 
and points calculated afterwards are not hltered by this. If not given, T3PS loads all 
points. 

Note that this may cause T3PS to calculate points twice. 

[parameter_space] files (string) List of hie names separated by (whitespace is 
signihcant!) to be used as additional source for known parameter space points. T3PS 
will not write to these hies. 

If the command line parameter —output_dir is set and a path given here is just 
a hie name, it is hrst looked for therein. Otherwise, each path is resolved using the 
same search rules as the “@include” statement. 
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[algorithm] likelihood (formula) Formula for the calculation of the likelihood quality 
criterion for all points. This can be negative. 

[algorithm] min_likelihood (float) The minimal likelihood value that a point in pa¬ 
rameter space has to have to be considered for further calculations. Points with 
values lower than this will still be saved in the “.data” hie, but will be treated as 
invalid for exploration. 

[algorithm] likelihood_steps (string) List of numerical values separated by comma 
specifying bins into which the likelihood of all points should be categorized. Example 
for bin interval determinations: 

“1, 2.71, 3.141” 

-(-oo, 1), [1,2.71), [2.71,3.141), [3.141, oo) 

During an iteration in state three, T3PS only considers points in the highest likeli¬ 
hood, non-empty bin for further exploration. Once more than the three most likely 
bins are fully depleted of boundary points to calculate neighbors for, points in the 
most likely bin are unloaded from memory - they still remain on disk in the “.data” 
hie, but are ‘forgotten’ to save memorjj^ If not given, the only likelihood bin is 

(-CX), oo). 

This is only used in state three iterations. 

[algorithm] disabled_states (string) List of algorithm states (separated by comma, 
as integers) that shall not be used for the scan. Note that one cannot disable state 
three without specifying projections. 

[algorithm] projection_count (integer) The number of projections dehned in the 
scan dehnition hie. Defaults to 0. Note that you must dehne at least as many 
projections as specihed here, while surplus projections are ignored. 

[algorithm] projection_i (formula) Formula for the combined specihcation of x and 
y value (separated by comma) to which points are projected. All projections are 
counted starting from i = 0. 

[algorithm] projection_i_x 

[algorithm] pro jection_i_y (formula) Separate formulas for x and y projection coor¬ 
dinates. Either these two or pro jection_z can be used. 

[algorithm] pro jection_i_z (formula) Formula for z coordinate analogous to x and y. 
If this directive is not specihed, it defaults to the likelihood as given in likelihood 
in the algorithm section. 

you absolutely cannot tolerate duplicates in the result data set, you should probably not use this 
directive. 
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[algorithm] pro jection_i_filter (formula) Formula for a condition that points have 
to fulhll to be considered for the calculation of the i’th projection. If not given, all 
valid points are considered for the projection calculation. 

[algorithm] extrapolated_pro jections (string) The list of projection indices (start¬ 
ing from 0 and separated by comma) of the projections for which interpolation and 
extrapolation should be done to smoothen the x-y-z,nax graph. If not given, all pro¬ 
jections are interpolated and extrapolated. 

[algorithm] symmetry_count (integer) The number of symmetry transformation ap¬ 
plied to projected points in state one iterations. Defaults to 0. Note that you must 
dehne at least as many symmetries as specihed, while surplus symmetries are ignored. 

[algorithm] symmetry _i (formula) The list of transformation (sub-)rules (separated by 
comma) of the form “par_ident: formula”, where “par_ident” can be one of the 
following: an index (starting from 0) into the list of parameters, a (Python) string 
specifying the parameter name, a Python identiher corresponding to the parameter 
name. The expression “formula” then gives the value the selected parameter should 
be changed to. 

Examples for symmetries: 

# All of these symmetries do the same thing 

# (assuming par_names = x, y, phi) 
symmetry_0= 2: pars.phi - pi, 0: -pars.x 
symmetry_l= "phi": pars.phi - pi, "x": -pars.x 
symmetry_2= phi: pars.phi - pi, x: -pars.x 


This transformation will then be applied to the points having maximal likelihood for 
(at least) one x-y point in one of the projection plains (in state one). The resulting 
points will then be calculated as well. Note that resulting points that do not fall 
onto the grid and those where the symmetry transformations generate an error, are 
ignored. 


4 Command Line Interface 

T3PS can be started from the command line using the following structure and options: 

t3ps [-h] [-v] [--mode MODE] 

[-P] [—pars VALUE [VALUE ...]] 

[-0 output_dir] [-p PORT] [input_file] 

Positional arguments: 

input_file Scan dehnition hie specifying the parameter scan. If not given, T3PS will 
show a menu with hies to choose from. If multiple hies are specihed, they are read 
in sequence and interpreted as one scan dehnition. The last hie given determines the 
name applicable to output hies such as “.data” hies and others. 
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Optional arguments: 

-h, —help Print out help message for the command line interface and exit. 

-V, — version Print out T3PS version and exit. 

—mode (string) Can be used to temporarily override the setting mode of the setup section 
in the scan dehnition hie without changing it. This specihes which algorithm should 
be used. Possible values are “scan”, “mcmc”, “optimize”, “explorer”, “worker” or 
“test”. 

-o, —output_dir Directory in which data and other hies for the requested scan should 
be written to. T3PS will create it if necessary. Defaults to the current working 
directory. 

“P? —port (integer) Can be used to temporarily override the setting given in port (in 
the setup section) in the scan dehnition hie without changing the hie. This specihes 
the port that T3PS uses to listen for requests in “worker” mode. 

—pars (string) Space-separated list of parameter values to be used in “test” mode (ig¬ 
nored in other modes). Multiple parameter points can be specihed using “—pars” 
multiple times. These points will be processed before any user input, if given. 

-P, —profiling If present, this causes T3PS to print out so called prohling information 
in test mode if processing is done on the local computer. This only concerns code 
run in Pythonj^ so it is only useful for more sophisticated point processors. 

-D, —debug Enable debug mode. This causes T3PS to output some additional informa¬ 
tion. 

—randomseed Use a specihc seed for the pseudo-random number generator. This can be 
used to make calculations involving random numbers deterministic between diherent 
instances of T3PS. 

Regardless of how the scan dehnition hie is given, T3PS will hrst show an overview of 
the processed conhguration before it will evaluate or calculate anything. If everything is 
in order and the user agrees, T3PS starts or resumes the scan. In “scan” and “mcmc” 
mode, the program will show an overview of the current overall progress, an estimated 
time of completion of the scan and some more possibly useful information. In “optimize” 
and “explorer” mode, there is only a subset of such information available and completion 
estimation is only done where feasible, i.e. for sub-tasks with a dehned length of calculation. 

The user can interrupt any calculation at any time using the Ctrl-l-c key combination on 
the keyboard. Calculations can then be resumed by launching T3PS again with the same 
—output_dir and scan dehnition hie name. On resuming, T3PS will try to continue in 

^^External code will only be listed as one big call to a function in the “subprocess” Python module and 
will have no substructure. 
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exactly the state it was in before. In some cases, this may mean that points have to be 
calculated more than once, but T3PS will try its best that they will only be saved once in 
the result data set. 

Warning: T3PS will not check whether the scan dehnition file changed while it was 
interrupted. Therefore, we advise caution to not accidentally mix up incompatible data 
sets. 


5 Using Multiple Computers 

Every instance of T3PS that is running with a scan dehnition that has a non-empty 
workers directive (in the setup section) and a mode that is not “worker” is considered 
a manager instance. Manager instances delegate their calculation to the worker instances 
reachable by the addresses given in workers in addition to the local processes governed 
by the value given in concurrent-processors in the setup section. All workers are as¬ 
signed work proportional to their respective concurrent-processors values. The mode 
under which the manager instance runs is not relevant to worker instances as they only 
calculate data for points in parameter space requested by manager instances. Worker in¬ 
stances generally ignore specihed parameter ranges and process whatever parameter values 
they are given. 

Worker instances can be used by multiple manager instances at the same time. However, 
they will return their results in the order in which they were requested, which can lead to 
signihcant delays when used by multiple manager instances. While running in “worker” 
mode, T3PS will show a list of the currently requested point batches and the last ten 
complete ones. 

Note that worker instances do not notice when manager instances are interrupted and 
will continue calculating what they are tasked with, if not interrupted themselves. 

The scan dehnition options relevant for the manager/worker architecture are the fol¬ 
lowing (in the setup section): 

workers (string) Comma-separated list of IP addresses or network names and ports under 
which worker instances are reachable. Each list entry is expected to have the form 
“address):port]”, where the port defaults to 31415. 

Example: 

machineA, machineB:15707, 192.168.0.123 

port (integer) Specihes the port under which T3PS should listen in “worker” mode. De¬ 
faults to 31415 if not present. The port must be between 1 and 65535 and must not 
already be in use. 

authkey (string) Shared secret or authorization key shared among all instances (both 
manager and workers) participating in the same calculation. This should be used 
to make sure scan dehnitions of manager and worker instances are compatible with 
each other and that no unauthorized access is possible. 
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concurrent_processors (integer) This number is specific to the running T3PS process 
whether it is running in manager or worker mode and has no infiuence on other 
machines. 

unit_length (integer) If the default value is used for this directive and it depends on 
the number of concurrent processes, it will be updated once a survey of all available 
worker instances has been done, to include the full number of processes. 


6 Included Point Processors 

6.1 The Minimal Processor “ExampleProcessor” 

Very simple point processor, which only demonstrates the structure of a typical point 
processor and a few possibly useful functions and tricks. Other than that, it has no 
configuration, does no calculation and returns an empty list of data values. 


6.2 The Simple Processor “SimpleProcessor” 


This point processor runs a user-supplied program with the substituted template file as 
command line argument and extracts all integer and floating point numbers that are not 
part of a word from the command’s outputp^ It is considered an error, i.e. leads to exclusion 
of a point, if the called program returns a non-zero exit code or takes too long. For a usage 


example, see sec. 7.1 


This processor supports the following directives in its own SimpleProcessor section: 


program (command line) Single command that shall be launched with the substituted 
template file as last argument in the directory containing it. If the first part of the 
given value is just a name, it is first resolved using the path environment variable 
(so just like in a regular shell). If it is not found this way, it is looked up using the 
same search rules as the include” statement. 


timeout (integer) Number of seconds the point processor waits for the program to com¬ 
plete its calculation. Defaults to 10. Note that this applies per point. 

data_values (formula) Formula that evaluates to the data of interest contained in the list 
of numbers extracted from the program’s output. Can be a single or multiple values 
contained in a Python list-like object. This expression has access to the Python 
variables pars and vars, as well as the list values, which contains the extracted 
numbers, and all mathematical functions and helperjtiodules as other formulas 
do. 

^^The number matching behavior can be tested from the shell using the command line: 

$ program | python SimpleProcessor.py 

which will echo the output of program and will mark matched numbers with indices from the front and 
back attached. 
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Some examples: 


data. 

_values 

= values[0], 

values[10] / 

pars [0] 

data. 

_values 

= [values[1] 

for 1 in [1, 

4, 9]] + 



[2 * values[6]] 



The simple processor will show its derived conhguration directly after its initialization. 


6.3 Analyzing SLHA Files with “SLHAProcessor” 


This point processor turns a substituted template file over to a Susy Les Houches Accord 
(SLHA) [7] compliant spectrum generator or similar. It then reads and parses the resulting 
SLHA output hle^^ extracts a user-dehned set of data values and returns them to T3PS. 


For a usage example, see sec. 7.3 


It has the following custom scan dehnition directives in the SLHAProcessor section: 


program (string) The command line used to process the template SLHA input hie. The 
syntax corresponds to a basic subset of the Unix shell syntax. The supported features 
include full quotation handling, input and output redirection using “< file” and 
“> file” and chaining of commands using either '&&’ or new line characters as 
delimiter (however, beware of misinterpretations of ’ as comments). In contrast to 
normal shell script, all three delimiters are equivalent and execution is aborted as 
soon as a command returns a non-zero exit code. 

The substituted template file can either be referenced by path using the sub-string 
“{template}” as command line argument or will be passed to the standard output 
of the hrst command if referenced nowhere this way. 

All binaries are looked up following the same rules as the program directive of the 
SlmpleProcessor and are executed in the directory of the substituted template file. 

Examples for valid program directives: 

# running of &&-separated list like in shell 
program = foo && bar && baz 

# equivalent to the above: 
program = foo; bar; baz 

# multi-line also the same (and maybe cleaner) 
program = foo 

bar 

baz 

# input redirection is supported 

# beware: only begins comment if 

# whitespace in front of it! 

program = foo < infile > outfile; no comment 
program = foo < infile > outfile ; comment 

^^The parser result can be reviewed using the command line: 

$ python SLHAProcessor.py file.slha 
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# redirections overwrite each other 
program = foo > filel > file2 

# -> only file2 is created and written to 

# file name patterns and variable expansion 

# are not supported 

program = echo *.scan $PATH > listing 

# -> listing contains; "*.scan $PATH" 

# special characters and whitespace can be 

# escaped just as in POSIX shells 
program = three\ word\ program with_argument 
program = "weirds&name" && html\<tags\>in_name 

# if {template} is given as parameter, it is 

# replaced with the path to the substituted 

# template file upon execution 
program = process_argument {template} 

# if {template} is not used anywhere, it is 

# automatically fed to the stdin of the first 

# command 

program = process_stdin 

# is equivalent to 

program = process_stdin < {template} 


timeout (integer) Number of seconds the point processor waits for the program to com¬ 
plete its calculation. Defaults to 10. Note that this applies per point. 

slha_files (string) List of hie names separated by (whitespace is signihcant except 
for leading and trailing one of full lines!) that shall be parsed as SLHA hies for the 
selection and evaluation of data. 


slha_data (formula) Python code that evaluates to the requested data contained in the 
SLHA hies specihed in the slha_files directive. Can be a single or multiple values 
contained in a Python list-like object. 


This formula expression has access to the same mathematical functions and constants 
as the formula input detailed in sec. 2.2.3 - including the pars and vars variables 
~ as well as to the object “sltia”. 


The “sltia” object gives access to the parsed SLHA data in the following way: 

# access to BLOCKS with/without scale Q: 

# slha[file_index][block, Q][index] 

# slha[file_index][block][index] 

# Higgs mass 

slha[0] {"MASS"] [25] 


27 









#3, 3 entry of up-type Yukawa matrix 

# at or near scale Q=1000 GeV 

slha[0]["YU", 1000][3, 3] 

# "index-less" ALPHA block 

slha[0]["ALPHA"][{)] 

# BLOCKS are also usable as Python matrices 

# Careful: indices start from 0! 
slha[0] .matrix ("YU") [i] [j] 

# (also includes an IMYU BLOCK if it exists) 

# access to DECAY blocks 

# slha[file_index]["DECAY"][pdgcode][index] 

# gluino(1000021) decay width 

slha[0] ["DECAY"] [1000021] ["width"] 

# gluino decay branching ratio to 

# 2 particles, namely ~d_L(1000001) dbar(-l) 

slha[0]["DECAY"][1000021][2, 1000001, -1] 


where file_index is an index (starting from 0) into the list of parsed SLHA hies 
specihed in the slha_files directive. 


For BLOCKS, the index/valne distinction is made snch that (except for special 
casee^®) the last entry on each data line is treated as the valne and the preceding 
entries as the index. For DECAY blocks, the hrst entry in each data line is treated 
as the valne and the rest as index. If no index entries exist, e.g. in the case of the 
“ALPHA” block of the SLHA, the valne can be accessed via the index “()” (empty 
tnple). 


Block names are case insensitive and reqnesting a block with a specihc scale Q hnds 
the block with the nearest valne to the one reqnested, bnt gives a warning if it differs 
by more than 1% (only visible in “test” mode). 


Thns, an example scan dehnition section that canses “MySpectrumGenerator” to be called 
with the substituted template file as its single command line argnment, lannches another 
analysis program on the generated “Spectrum” file and then reads out some result values 
would look like the following: 

[SLHAProcessor] 

program = MySpectrumGenerator {template} > Spectrum 
Analyser Spectrum > Analysis.SLHA 
slha_files = Spectrum:Analyis.SLHA 
slha_data = slha[0]["MASS"][25], 
slha[0] ["MASS"] [1000021], 
slha[0] ["YU", 1000] [3, 3] , 

^®In the current version of T3PS, these special BLOCKs are: FOBS, FOBSSM, FOBSERR, FMASS, 
FPARAM, FCONSTRATIO, HiggsBoundsInputHiggsCouplingsBosons and HiggsBoundsInputHiggsCou- 
plingsFermions. For details, see and the source code of the SLHAProcessor module. 
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slha[0] ["DECAY"] [1000021] ["width"], 
slha[0]["DECAY"][1000021][2, 1000001, -1], 
slha[l]["SOMECOMPLETELYDIFFERENTANALYSIS"][()] 


The SLHA processor will show its derived conhguration directly after its initialization. 
Note that there is no check whether the number of names given in the data_names directive 
(in the parameter_space section) is consistent with the value of the slha_data directive. 

6.4 Multiple Point Processors with “ProcessorChain” 

This processor can be used to combine two or more processors in the same scan. For this, 
it reads exactly one directive in its own ProcessorChain section. 

point-processors (string) List of hie names separated by (whitespace is signihcant 
except for leading and trailing one of full lines!) of the point processor modules that 
shall be combined. The order is signihcant. 

The ProcessorChain processor passes each point to the point processors in the order 
in which they are given. The resulting list of data values is then the concatenation of the 
sub-data lists in that same order. 

If one point processor occurs multiple times in the list, both instances can be conhgured 
diherently by prehxing the relevant scan dehnition section with “ProcessorChainih”, where 
i is the index of the relevant point processor in the list (starting from 0). The point processor 
will then see the prehxed section merged with all unprehxed sections. 

Usage example: 

[ProcessorChain] 

point_processors = Processor:Processor 

[Processor] 
namel = foo 
name2 = bar 

[ProcessorChain:0:Processor] 
namel = baz 

[ProcessorChain:1:Processor] 
name2 = baz 

# -> first will see namel=baz, name2=bar 

# second will see namel=foo, name2=baz 


7 Example Scan Definitions 

This section demonstrates how T3PS can be instructed to perform parameter scans for 
several types of calculations. It contains the following scans with their show-cased features: 
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Scalar Dark Matter “test” mode, “scan” mode for grids, usage of SimpleProcessor. 

Lepton Mixing and Charged Lepton Corrections “mcmc” and “optimize” modes, 
custom processors, text substitution, include” statement, variables, helper mod¬ 
ules. 

Maximal Higgs Mass in mSUGRA scattering scan mode, usage of SLHAProcessor, 
bounds, “explorer” mode, parameter space mode “file”, remote concurrency. 

All files needed to perform the example scans are included in the T3PS package, except 
for publicly available external code - for those, quick instructions for setting them up are 
included instead. In addition, also the data hies used for the hgures and results shown are 
included within the T3PS package. For details on how to exactly reproduce them, see the 
included “README” hie. 

7.1 Scalar Dark Matter 

In this example, we reproduce the results of [lO] where the standard model (SM) is extended 
by a real scalar gauge-singlet S that is supposed to be the single component of the dark 
matter (DM) relic density. To this end, we make use of the Z 3 symmetric dark matter 
model m implemented in micrOMEGAs3.6.9.2 da US] to calculate the dark matter relic 
density floM (“Omega_DM”) and dark-matter-nucleon cross-sections as,N (“sigma_S_N”) 
for N =p,n (proton and neutron) as a function of the scalar coupling A 51 (“laSl”) to the 
Higgs boson and the dark matter particle mass Ms (“ms”). 

Note that the model as implemented in micrOMEGAs actually includes a complex scalar 
gauge-singlet instead of a real one, so we have to divide ^Idm by two to directly compare 
it with HD]. To obtain the correct limit in all other aspects, the other scalar couplings of 
the Z 3 model will be set to zero and the surplus particles will be decoupled by setting their 
masses to 1000 TeV. The Higgs boson mass will be hxed to 125.7 GeV. 

For the calculation, we will use a slightly modihecj^ version of the code included in 
the micrOMEGAs package. The relevant binary (“main-Z3MH”) expects a “data.par” 
input hie given as command line argument, which can be written as the template hie 
“data.par.template”: 


Mh 

125.7 

Mdml 

$MS 

Mdm2 

1.0e6 

MHC 

1.0e6 

muppS 

0 

la3 

0 

la2 

0 

laS 

0 

laSl 

$laSl 


^^Namely, the following options in the file “main.c” of the “Z3MH” folder were disabled: 
MASSES_INFO, INDIRECT_DETECTION, NEUTRINO, DECAYS, CLEAN. This leaves only OMEGA 
and CDM_NUCLEON enabled. A patch file containing this modification is included in the T3PS package. 
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laS2 0 
laS21 0 
sinDm 0 


Since micrOMEGAs prints its results to the console, we choose to use “SimpleProcessor”. 
Looking at the usual output of the code, we see that VLdm is the 4’th number printed and 
the DM-nucleon cross-sections are given by the 8’th and 4’th number from the back (with 
a variable number of values in between). 

The scan dehnition hie “ScalarDM.scan” is then given by: 

[setup] 
mode = scan 

template = data.par.template 

point_processor = processors/SimpleProcessor.py 

[SimpleProcessor] 
program = main-Z3MH 

data_values = values[3], values[-8], values[-4] 

[parameter_space] 
par_names = laSl, MS 

data_names = Omega_DM, sigma_S_p, sigma_S_n 

par_laSl = Interval(0.01, 10) with count=200, distribution=log 
par_MS = interval(10, 10000) with count=200, distribution=log 

We will hrst test our scan dehnition by launching T3PS in “test” mode by running 

$ t3ps —mode test ScalarDM.scan 

As always T3PS will hrst show an overview of the settings as derived from the scan def¬ 
inition hie before any calculation is run. It will then ask the user directly for parameter 
values of points that shall be calculated leading to console interactions like the following 
(user input in bold): 

[. . .] 

# Enter point (format: laSl, MS; as numbers or 'random'): 

> 0.5, 1100 

# Parameters: 

laSl = 0.5, MS = 1100.0 

# Calculation done after: 0.041191 s 

# Data: 


Omega_DM : 0.111 i sigma_S_p: 1.779e-09 

sigma_S_n: 1.814e-09 | - : - 


# Output columns: 


1 : 0.5 I 2 : 1100.0 | 3 : 0.111 

4 : 1.779e-09 | 5 : 1.814e-09 |-: - 


[. . .] 
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Hdm / 2 



'^Sl 

Figure 2: The DM relic density Qdm d^s function of the two scalar DM model parameters. 
The hatched region is excluded by as,p being above the 90% CL bound as provided by the 
LUX experiment [TT] and obtained from DMTools [15]. Note that for better comparison 
with in. the relic density has been divided by two. 


If all our test input points yield satisfying results, we can launch T3PS in its configured 
mode using 

$ t3ps ScalarDM.scan 

and after some cross-checks by T3PS with the user, the scan is performed without much 
interaction and saved to the file “ScalarDM.scan.data” (among others). 

This file can then be read and turned into plots using the following code sketch for 
Mathematica 

points = Import ["ScalarDM.scan.data", "Table"]; 

ListContourPlot[points [[All, {1,2,3}]]] 

and for gnuplot 

splot "ScalarDM.scan.data" using 1:2:3 

(both examples for Qdm over A 51 -M 5 plots). The resulting contour plot for the DM relic 
density is shown in fig. As we can see, a comparison with fig. 2 b in (TU] yields only very 
small (and expected due to e.g. a different Higgs boson mass) differences. 

7.2 Lepton Mixing and Charged Lepton Corrections 

In this example scan, we will demonstrate the “optimize” and “mcmc” scan modes. For 
this, we choose to investigate how well the present global fit of the PMNS matrix can 
be reproduced by tribimaximal mixing in the neutrino sector and charged lepton mixing 
strictly between the first two generations. 
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Since the computation for this is relatively easy, we write our own point processor hie 

“fit_pmns.py”: 

# import SciPy for nicer matrix usage 

import scipy as sp 

# import some more mathematical functions 

from math import sin, cos, sqrt 
from cmath import exp 

def main{template_file, pars, vars): 

# we can also access pars and vars by name here 

thetal2e = pars.thetal2e 

sl2e, cl2e = sin(thetal2e), cos(thetal2e) 
deltal2e = pars.deltal2e 

UTBM = sp.matrix([ 

[-sqrt(2/3.), l/sqrt{3), 0], 

[ l/sqrt{6), l/sqrt{3), l/sqrt{2)], 

[ l/sqrt{6), l/sqrt{3), -l/sqrt{2)] 

] ) 

Ue = sp.matrix{[ 

[cl2e, sl2e * exp(lj * deltal2e), 0], 

[-sl2e * exp(-lj * deltal2e) , cl2e, 0], 

[0, 0, 1] 

] ) 

# m.H = hermitian transpose of m 

UPMNS = Ue.H * UTBM 

# indices are 0-based! 

sinl3 = abs (UPMNS[0,2]) 
tanl2 = abs (UPMNS[0,1] / UPMNS[0,0]) 
tan23 = abs (UPMNS [ 1,2 ] / UPMNS[2,2]) 
sinl2 = tanl2 / sqrt(l + tanl2 ** 2) 
sin23 = tan23 / sqrt(l + tan23 ** 2) 

return [sinl2, sin23, sinl3] 


As one can see, the code simply multiplies the tribimaximal mixing matrix UTBM with the 
charged lepton mixing matrix Ue and extracts the sin’s of the three mixing angles. 

The scan dehnition hie for hnding the best ht point (using the 2014 NuFIT values [16] 
as target) is then given by (as hie “ChargedLeptons_optimize.scan”): 

[setup] 

# do optimization with default population size 

# (10*2 = 20 in this case) 
mode = optimize 

# use our custom processor 

# (it uses no template file) 
point_processor = fit_pmns.py 
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[parameter_space] 

# two parameters that are angles in radians 

# (only interested in first quadrant for theta) 
par_names = thetal2e, deltal2e 
par_thetal2e = interval(0, 1.5707963267948966) 
par_deltal2e = interval(0, 3.141592653589793) 

data_names = sinl2, sin23, sinl3 

[algorithm] 

# fit to "NuFIT Free Fluxes + RSBL" 

# (use higher minimvim for theta23) 
chi_squared = ( 

{(data.sinl2 ** 2 - 0.304) / 0.012) ** 2 + 
{(data.sin23 ** 2 - 0.577) / 0.03) ** 2 + 
{(data.sinl3 ** 2 - 0.0219) / 0.0010) ** 2 

) 

likelihood = -(%(chi_squared)s) 


Note that, as introduced in sec. |3.1[ the placeholder string “% {chi_squared) s” is replaced 
with the value of the directive chi_squared. Being interested in the probability distri¬ 
butions of our parameters, we also calculate those using the Markov chain Monte Carlo 
algorithm (mode “mcmc”) using the scan dehnition hie “ChargedLeptons_mcmc.scan” 
(which extends the previous dehnition hie using “@include”): 


@include ChargedLeptons_optimize.scan 

[setup] 

# do MCMC analysis with chains containing 10000 

# points each 
mode = mcmc 
unit_length = 10000 

[parameter_space] 

# amend parameters with step sizes 

par_thetal2e = interval(0, 1.5707963267948966) with mcmc_stepsize=0.003 
par_deltal2e = interval(0, 3.141592653589793) with mcmc_stepsize=0.04 

[algorithm] 

# switch from a chi"'2 to a distribution function 

likelihood = exp(-0.5 * (% (chi_squared)s) ) 


Here, we used the information on the parabolas obtained from the “optimize” scan to 
get an estimate for the MCMC step sizes. 

In a hnal step, we will use the obtained information on 0f2 values for the electron 
and muon Yukawa couplings ye and |T7] to ht the parameters of a very simple havor 
model. For simplicity, we neglect mixing to the third generation and only consider the hrst 
two generations. The relevant Yukawa coupling matrix is then given by 



(1) 
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best £t value 

Icr uncertainty 

6*®2 in ° 

12.07 

+0.25 

-0.31 

6 I 2 in ° 

74.7 

±5.1 

sin2 0P"^NS 

0.304 

+0.12 

-0.11 

sin^^^T^s 

0.4888 

+0.0006 

-0.0004 

sin^^PgMNS 

0.0218 

± 0.0010 

a in 10 "^ 

1.36 

+0.04 

-0.03 

b in 10 "^ 

1.26 

±0.03 

c in 10 "“^ 

5.881 

+0.008 

-0.007 


Table 1: Statistical information obtained from the fit and MCMC analysis of charged lepton 
corrections to tribimaximal mixing. The Pearson correlation coefficient between the htted 
parameters Q \2 and 6^2 is 0.05 and the minimal is 8.64. The correlation coefficients 
between a, b and c are pat = -0.998, pac = 0.82 and pbc = -0.80. 


which is dehned to appear in the Lagrangian as The relevant equations 

has to fulhll to reproduce the Yukawa couplings and the mixing angle are given by 


det Ye\ = 2 /e • 2 /m , ll>"e|p = ye+yl, 


b ■ c 


tan 6*12 ) 


( 2 ) 


where we used a zeroth order approximation in yejy^i in the last equation and assumed all 
parameters to be real. Because the equation solving capabilities of standard Python are 
limited, we will again use the SciPy package. Since there is nothing else to calculate, we 
will omit the specihcation of a point processor and instead do the whole calculation using 
variables. The scan dehnition hie “ChargedLeptons_matrixfit.scan”, which solves the 
relevant equations is then given by 
[setup] 

helper_mociules = scipy. optimize : scipy . linalg 

[parameter_space] 
par_names = ye, ymu, thetal2e 

# numbers taken from arXiv:1306.6879 
par_ye = normalvariate(2.8501e-6, 0.0022e-6) 
par_ymu = normalvariate(6.0167e-4, 0.0044e-4) 

# ... and previous scans 

par_thetal2e = normalvariate{0.211, 0.005) 

var_names = a, b, c 

Y_e = [ [0, b] , [a, c] ] 

var_a = remember(a_b_c=scipy.optimize.fsolve( 
lambda (a, b, c): { 

abs(scipy.linalg.det(% (Y_e)s)) - 
(pars.ye * pars.ymu). 
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scipy.linalg.norm{%(Y_e)s) ** 2 - 

(pars.ye ** 2 + pars.ymu ** 2), 
abs (b * c / (a ** 2 + c ** 2)) - 
tan(pars.thetal2e) 

) , 

(2e-5, le-4 , 6e-4) 

) ) [ 0 ] 

var_b = remember("a_b_c")[1] 
var_c = remember("a_b_c")[2] 

mode = scatter 
point count = 100000 

As can be seen, we used the remember function to cache the result of numerical equation 
solving to avoid doing it again for each variable. 

Finally, all resulting statistical information of all three parameter scans is summarized 
in tab. [U 

7.3 Maximal Higgs Mass in mSUGRA 

In this example, we use the program SoftSUSY3.5.1 [H] to scan the mSUGRA parameter 
space and hnd the maximal possible Higgs boson mass over certain subspaces. The results 
are then compared with the ones found in the study in [TU] . 

We start by writing a template file in SLHA format [7]. For the parameter scan, we 
intend to vary all 4+1 mSUGRA parameters and use the same input parameters as in [19]. 
Thus we arrive at a file named “mSUGRA.slha.template” with the following content: 


Block 

MODSEL 


# 

Select model 

1 

1 



# sugra 

Block 

SMINPUTS 


# 

Standard Model inputs 

1 

1.2791600000+02 


# alpha"'(-1) SM MSbar(MZ) 

2 

1.1663700000-05 


# G_Fermi 

3 

1.1840000000-01 


# alpha_s(MZ) SM MSbar 

4 

9.1190000000+01 


# MZ(pole) 

5 

4.1900000000+00 


# mb(mb) SM MSbar 

6 

1.7290000000+02 


# mtop(pole) 

7 

1.7770000000+00 


# mtau(pole) 

Block 

MINPAR 


# 

Input parameters 

1 

$m0 



# mO 

2 

$ml2 



# ml2 

3 

$tanB 0 ta 



# tan beta at MZ, DRbar 

4 

$sign_mu 



# sign(mu) 

5 

$A0 



# AO 

Block 

SOFTSUSY # 

SOFTSUSY-specific 

1 

1.00-03 

# Nvimerical precision 

2 

0.0 

# Quark 

mixing parameter 

5 

1.0 

# 2-loop soft mass/trilinear RGEs 


Note that we disabled quark and general flavor mixing to make the analysis of superpartner 
masses not unnecessarily complicated. 
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For the parameter scan, we write the following scan dehnition to a hie with the 

“HiggsMass_scatterscan.scan”: 

[setup] 
mode = scan 


# use our template and the SLHAProcessor 
template = mSUGRA.slha.template 
point_processor = processors/SLHAProcessor.py 


[SLHAProcessor] 

# command line syntax as per SoftSUSY manual 

program = softpoint.x leshouches < [template] > SLHASpectrum 


slha_files = SLHASpectrum 


# extract several masses from the spectrvim file 

# (for the PDG code meanings, see data_names) 


slha_data = slha 
slha[0]["MASS"] 
slha[0]["MASS"] 
slha[0]["MASS"] 
slha[0]["MASS"] 
slha[0]["MASS"] 
min ( [ 

slha[0]["MASS 
for code in [ 
] ) , 

slha[0]["MASS"] 
slha[0]["MASS"] 


[0] ["MASS"] [25], 
[1000022],slha[0] 
[1000006],slha[0] 
[1000021], 
1000001],slha[0] 
2000001],slha[0] 

][code] 

000012, 1000014, 

2000011],slha[0] 
1000015],slha[0] 


["MASS"] [1000024], 
["MASS"][2000006], 

["MASS"] [1000002], 
["MASS"] [2000002], 


1000016] 

["MASS"][2000013], 
["MASS"] [1000005] 


[parameter_space] 

# mSUGRA has 5 parameters: 

par_names = mO, ml2, AO, sign_mu, tanBeta 


# scan over the following continuous ranges: 

par_mO = interval(50, 3000) 

par_ml2 = interval(50, 3000) 

par_A0 = interval(-9000, 9000) 

par_tanBeta = interval(1, 60) 

# (except for the sign of mu of course) 
par_sign_mu = - 1 , 1 


# give names to all the masses 
data_names = mhO, 
mNl, mCl, 
mstopl, mstop2, 
msG, 

msdL, msuL, 
msdR, msuR, 
msNu, 

mseR, msMuR, 


name 
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msTaul, msb 


# impose three constraints 
bound_count = 3 

# MSUSY must be below 3 TeV 

bound_0 = sqrt(data.mstopl * data.instop2) < 3000 

# masses have to satisfy current PDG bounds 
bound_l = data.mNl > 46 

and (data.mCl > 94 or pars.tanBeta > 40 
or data.mCl-data.mNl < 3) 
and (data.msNu > 94 or pars.tanBeta > 40 
or data.mseR-data.mNl < 10) 
and data.mseR > 107 

and (data.msMuR > 94 or pars.tanBeta > 40 
or data.msMuR-data.mNl < 10) 
and (data.msXaul > 81.9 

or data.msTaul-data.mNl < 15) 
and min(data.msuL, data.msdL, data.msuR, 
data.msdR) > l.lle3 

and (data.msb > 89 or data.msb-data.mNl < 8) 
and (data.mstopl > 95.7 

or data.mstopl - data.mNl < 10) 
and data.msG > 800 

# the neutralino shall be the LSP 
bound_2 = data.mNl <= min( 

data[i] for i in range(len(data)) if i != 0 

) 

# do a random scan 
mode = scatter 
point_count = 100000 

As can be seen, we perform a “scatter” scan where we calculate 100000 points taken at 
random from a set of continuous or discrete ranges. For the bounds, we stuck to the 
constraint Msusy < 3 TeV as also imposed in [I9] and used the bounds as given in [20] for 
the superpartner masses. 

We then let T3PS run the parameter scan, which is complete after about 105 minutes 
(on a 3.4 GHz Intel i7 quad core processor). The resulting plots can be seen in £g. 

A comparison with the analogous plots of [12] (£g. 3 a-d therein) shows that both have 
almost the same behavior with only minor differences that can be attributed to more 
rigorous constraints for the superpartner spectrum in |19j . 

As an additional rehnement, one might be interested in the maximal Higgs boson 
mass over two-dimensional parameter subspaces instead of one-dimensional ones. This 
would involve binning the randomly distributed points appropriately in the respective 
plain. Instead, we go for an automatically binned strategy involving a discrete grid 
over which we scan our five mSUGRA parameters. The corresponding scan dehnition 
hie “HiggsMass_gridscan.scan” only has a few lines: 

|@include HiggsMass_scatterscan.scan 
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[parameter_space] 
mode = grid 

par_mO = interval(200, 2000) with count = 10 
par_ml2 = interval(200, 3000) with count = 10 
par_A0 = interval(-9000, 9000) with count = 20 

par tanBeta =1, 2,..., 5, 7.5,..., 30, 33,..., 60 

Again after about 95 minute^^ (on the same 3.4 GHz Intel i7 quad core processor), T3PS 
has hnished the scan. The resulting plots for one-dimensional subspaces are shown in fig. 
with (as expected) good agreement with the previously obtained data set. 

An additional feature of T3PS is the so called “explorer” mode. This mode is exactly 
designed for this sort of calculation, i.e. maximizing a given function over several different 
plains in parameter space. Adapting our grid scan to this mode is not complicated and 
yields the following scan definition file “HiggsMass_explorer.scan”: 

@include HiggsMass_gridscan.scan 

[setup] 

mode = explorer 

[algorithm] 

# maximize the Higgs boson mass! 
likelihood = data.mhO 
min_likelihood = 118 

# calculate maximal Higgs boson mass over several 

# different planes (or lines) 
projection_count = 7 
projection_0 = pars.mO, pars.mO 
projection_l = pars.inl2, pars.ml2 
projection_2 = pars.AO, pars.AO 
projection_3 = pars.tanBeta, pars.tanBeta 

projection_4 = pars.mO, pars.ml2 

projection_5 = pars.mO, pars.AO 
projection_6 = pars.ml2, pars.AO 

# two (probably not very good) symmetries 
symmetry_count = 2 

# no dependence on sign of mu? 
symmetry_0 = sign_mu: -pars.sign_mu 

# no dependence on sign of AO? 
symmetry_l = 2: -pars[2] 

# only do state one calculation 
disabled_states =2, 3 


After running this scan for about 5 minutes, we find analogous plots to the two previous 

^^Differences to the scattering scan are to be expected since the parameter ranges slightly differ between 
scatter and grid scan. 
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scans as shown in fig. Additionally, we can compare plots of the maximal Higgs boson 
mass over some two-dimensional plains as shown in fig. As can be seen, the differences 
are already very small compared to the calculation of the full parameter space grid. 

Note that there are multiple ways to improve the data obtained using the “explorer” 
mode. For example, one can simply enable algorithm states two and three and let T3PS 
run longer. On the other hand, keeping in mind that in this example the starting points 
were chosen at random, one can also choose those more carefully. This can be done by 
hand using the “test” mode and consequently using the “.testdata” file as input or by 
running a scan in the “optimize” mode beforehand and thereby creating an already nearly 
optimal starting point set. 

As final part of this example, we will compare the results obtained with SoftSUSY with 
what we would have gotten with SPheno3.3.3 [an [22]. For demonstration purposes, we 
will make use of the manager-worker architecture, too. The content of the scan definition 
file “HiggsMass_recalc.scan” is then given by: 

@include HiggsMass_explorer.scan 

[setup] 
mode = scan 
workers = 127.0.0.1 
authkey = HiggsMass_recalc 

[SLHAProcessor] 

program = SPheno {template} SLHASpectrum 

[parameter_space] 
mode = file 

files = HiggsMass_explorer.scan.data 

file_columns = mO, ml2, AO, sign_mu, tanBeta, mhO 

par_mO = file.mO 

par_ml2 = file.ml2 

par_A0 = file.AO 

par_sign_mu = file.sign_mu 

par_tanBeta = file.tanBeta 

[algorithm] 

out_columns = pars.mO, pars.ml2, pars.AO, 

pars.sign_mu, pars.tanBeta, data.mhO - file.mhO 


Note that the used version of SPheno does not make use of exit codes to signal invalid 
parameters. However, it will write an incomplete SLHA spectrum file instead, which will 
lead to errors from SLHAProcessor due to a missing “MASS” block. 

As can be seen, we use the parameter space mode “file”. This means that the parameter 
space is taken directly from the points contained in the output file of the “explorer” scan. 
The parameter values are simply taken one-to-one from the data file. The out_coluinns 
directive causes that only the specified values are saved to the result file instead of all 
parameter and calculated data values. Finally, the worker instance of T3PS can be launched 
using 
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$ t3ps HiggsMass recalc.scan —mode worker 


As shown in fig. both codes only differ by abont 1.5 GeV in their Higgs mass result. 
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A Implemented Algorithms 

A.l Markov Chain Monte Carlo 


The implemented Metropolis-Hastings algorithm m - starting from a point pO - can be 
sketched as: 

While count_points < requested_count_points: 

pi = new_random_point_around(pO, stepsizes) 

If pi is excluded by prior: 

stay_count = stay_count + 1 

Redo 

Else If pi is excluded by constraints: 
stay_count = stay_count + 1 

Redo 

End 

LI = L(pl) * prior(pl) 

LO = L(pO) * prior(pO) 

a = random_uniform(0, 1) 

If a < min(Ll / LO * q(p0, pi) / q{pl, pO), 1): 

Save pO (with stay count) 
pO = pi 

stay_count = 1 

count_points = count_points + 1 

Else: 

stay_count = stay_count + 1 

End 

End 

where L (p) is the propagation likelihood value for the point p and q (pi, pO) is the pro¬ 
posal density (up to normalization) for the point pi around pO. In the case of flat prior 
probability, L corresponds to the target probability distribution function (up to normal¬ 
ization). For the relevant scan dehnition directives, see sec. 


A.2 Optimization using Differential Evolution 

The implementation of the differential evolution algorithm |5] as applied to a htness func¬ 
tion f can be sketched as: 

While waiting < max_waiting_tiine: 

For each x in population: 

a, b, c = Find three random points 
in population with 
a ^ b c ^ a and a, b, c =#= x 
xs = a + S * (b - c) 

For i from 1 to count_dimensions: 
r = random_uniform(0, 1) 

If r < rho: 

y[i] = x[i] 

Else: 


3.5 
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Y [i] = xs [i] 

End 

End 

If f (y) > f (X) : 

Replace x -> y in population 

End 

End 

new = max{f(x) for x in new population} 
old = max{f(x) for x in old population} 
If abs(new - old) < eps + eps_rel * old: 
waiting = waiting + 1 

Else: 

waiting = 0 

End 

End 


where S € [0,2] is the differential weight (default: 0.6), rho € [0,1] is the crossover prob¬ 
ability (default: 0.5), eps is the absolute waiting threshold (default: 0) and eps_rel is 
the relative waiting threshold (default: 10"® for double precision) ~ the population size 
defaults to 10 times the number of parameters with at least two possible values. For more 
information on the choice of these algorithm parameters, see e.g. [23]. For the relevant 


scan definition directives, see sec. 3.6 


Note that, after the last iteration, one has to extract the point with highest fitness 
value from the last population. 


A.3 Swarm-like Explorative Optimization 

Each iteration of the algorithm starting from a known point set S can be sketched as: 

If projections defined and state < 3: 

For each projection in projections: 

For each p in S': 

If state > 1 or p ^ boundary(S) : 

Next 

End 

X, y, z = projected_coordinates{ 
projection, p 

) 

If z > z_max(x, y): 
p_max{x, y) = p 
z_max(x, y) = z 

End 

End 

If state = 1: 

For each x, y in projected_plain: 

Add neighbors(best_point[x, y]) to V 
For dx, dy in simple_orbit{0): 

Add points from line segment 

[p_max(x, y) p_max(x+dx, y+dy)] 
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to V 

Add points encountered by extending 
previous line segment to V 
Apply symmetries to p_max{x, y) 
and add result to V 

End 

End 

End 

End 
Else: 

For each p in S': 

If 3 n with n € neighbors(p) and n ^S 

Add p to boundary bin Bi according to L(p) 

End 

End 

B = highest likelihood, non empty Bi 

For each p in S: 

Add neighbors(p) to V 

End 

End 

If V is empty: 

If state < 3: 

state = state + 1 

End 
Else: 

For each p in V \ S: 

Process p and add it to S 

End 

If projections defined: 
state = 1 

End 

End 

V = {} 


where L (p) is the likelihood function value for the point p. For the relevant scan dehnition 


directives, see sec. 3.7 
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Figure 3: Value of the Higgs boson mass m/^o as function of each of the four continuous 
mSUGRA parameters (marginalizing over the others each time) as found in the scattering 
scan. No further constraints than the ones in the scan dehnition hie were applied. 


130 
128 
I 126 

124 

122 

120 


0 


500 


1000 1500 

mo / GeV 


2000 




mi/2 / GeV 



Figure 4: Value of the Higgs boson mass rriho as function of each of the four continuous 
mSUGRA parameters (marginalizing over the others each time) as found in the grid scan. 
No further constraints than the ones in the scan dehnition hie were applied. 
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Figure 5: Value of the Higgs boson mass m^o as function of each of the four continuous 
mSUGRA parameters (marginalizing over the others each time) as found in the “explorer” 
scan. No further constraints than the ones in the scan dehnition hie were applied. 


48 













































m^o / GeV 

119 121 123 125 127 




500 1000 1500 2000 


-8000 -6000 -4000 -2000 0 


-8000 -6000 -4000 -2000 0 


niQ / GeV 


Ao / GeV 


Ao / GeV 


2000 I 



500 1000 1500 2000 


-8000 -6000 -4000 -2000 0 


-8000 -6000 -4000 -2000 0 


Figure 6: Maximal value of the Higgs boson mass 171^0 as function of the four continuous 
mSUGRA parameters (marginalizing over the others) as found in the grid (upper) and 
“explorer” (lower) scan. 



Figure 7: Difference between the Higgs mass as calculated by the codes SoftSUSY and 
SPheno for the points found in the “explorer” scan. 


49 
































